home *** CD-ROM | disk | FTP | other *** search
- *cmdline.txt* For Vim version 5.1. Last modification: 1998 Mar 25
-
-
- VIM REFERENCE MANUAL by Bram Moolenaar
-
-
- Command-line mode *mode-cmdline* *:*
-
- Command-line mode is used to enter Ex commands (":"), search patterns
- ("/" and "?"), and filter commands ("!").
-
- 1. Command line editing |cmdline-editing|
- 2. Command line completion |cmdline-completion|
- 3. Ex command lines |cmdline-lines|
- 4. Ex command line ranges |cmdline-ranges|
- 5. Ex special characters |cmdline-special|
-
- ==============================================================================
- 1. Command line editing *cmdline-editing*
-
- Normally characters are inserted in front of the cursor position. You can
- move around in the command line with the left and right cursor keys. With the
- <Insert> key, you can toggle between inserting and overstriking characters.
- {Vi: can only alter the last character in the line}
-
- Note that if your keyboard does not have working cursor keys or any of the
- other special keys, you can use ":cnoremap" to define another key for them.
- For example, to define tcsh style editing keys: *tcsh-style*
- > :cnoremap <C-A> <Home>
- > :cnoremap <C-F> <Right>
- > :cnoremap <C-B> <Left>
- > :cnoremap <Esc>b <S-Left>
- > :cnoremap <Esc>f <S-Right>
- (<> notation |<>|; type all this literally)
-
- *cmdline-history*
- The command lines that you enter are remembered in a history table. You can
- recall them with the up and down cursor keys. There are actually three
- history tables:
- - one for ':' commands
- - one for search strings
- - one for expressions
- These are completely separate. Each history can only be accessed when
- entering the same type of line.
- Use the 'history' option to set the number of lines that are remembered
- (default: 20).
- Notes:
- - When you enter a command line that is excactly the same as an older one, the
- old one is removed (to avoid repeated commands moving older commands out of
- the history).
- - Only commands that are typed are remembered. Ones that completely come from
- mappings are not put in the history
- - All searches are put in the search history, including the ones that come
- from commands like "*" and "#". But for a mapping, only the last search is
- remembered (to avoid that long mappings trash the history).
- {Vi: no history}
-
- There is an automatic completion of names on the command line; see
- |cmdline-completion|.
-
- *c_CTRL-V*
- CTRL-V Insert next non-digit literally. Up to three digits form the
- decimal value of a single byte. The non-digit and the three
- digits are not considered for mapping. This works the same
- way as in Insert mode (see above, |i_CTRL-V|).
- *c_CTRL-Q*
- CTRL-Q Same as CTRL-V.
-
- *c_<Left>*
- <Left> cursor left
- *c_<Right>*
- <Right> cursor right
- *c_<S-Left>*
- <S-Left> or <C-Left> *c_<C-Left>*
- cursor one WORD left
- *c_<S-Right>*
- <S-Right> or <C-Right> *c_<C-Right>*
- cursor one WORD right
- CTRL-B or <Home> *c_CTRL-B* *c_<Home>*
- cursor to beginning of command line
- CTRL-E or <End> *c_CTRL-E* *c_<End>*
- cursor to end of command line
-
- *c_<LeftMouse>*
- <LeftMouse> cursor to position of mouse click.
-
- CTRL-H *c_<BS>* *c_CTRL-H*
- <BS> delete the character in front of the cursor (see |:fixdel| if
- your <BS> key does not do what you want).
- *c_<Del>*
- <Del> delete the character under the cursor (at end of line:
- character before the cursor) (see |:fixdel| if your <Del>
- key does not do what you want).
- *c_CTRL-W*
- CTRL-W delete the word before the cursor
- *c_CTRL-U*
- CTRL-U remove all characters
-
- Note: if the command line becomes empty with one of the
- delete commands, Command-line mode is quit.
- *c_<Insert>*
- <Insert> Toggle between insert and overstrike. {not in Vi}
-
- {char1} <BS> {char2} or *c_digraph*
- CTRL-K {char1} {char2} *c_CTRL-K*
- enter digraph (see |digraphs|). When {char1} is a special
- key, the code for that key is inserted. {not in Vi}
-
- CTRL-R <0-9a-z"%#:-=> *c_CTRL-R*
- Insert the contents of a numbered or named register. Between
- typing CTRL-R and the second character '"' will be displayed
- to indicate that you are expected to enter the name of a
- register. The text is inserted as if you typed it, but
- mappings and abbreviations are not used. Special registers:
- '"' the unnamed register, containing the text of
- the last delete or yank
- '%' the current file name
- '#' the alternate file name
- ':' the last command line
- '-' the last small (less than a line) delete
- '=' the expression register: you are prompted to
- enter an expression (see |expression|)
- Note: The '.' register (last inserted text) is not available
- here. See |registers| about registers. {not in Vi}
-
- CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>*
- <CR> or <NL> start entered command
- *c_<Esc>*
- <Esc> When typed and 'x' not present in 'cpoptions', quit
- Command-line mode without executing. In macros or when 'x'
- present in 'cpoptions', start entered command.
- *c_CTRL-C*
- CTRL-C quit command line without executing
-
- *c_<Up>*
- <Up> recall older command line from history, whose beginning
- matches the current command line (see below).
- *c_<Down>*
- <Down> recall more recent command line from history, whose beginning
- matches the current command line (see below).
-
- *c_<S-Up>* *c_<PageUp>*
- <S-Up> or <PageUp>
- recall older command line from history
- *c_<S-Down>* *c_<PageDown>*
- <S-Down> or <PageDown>
- recall more recent command line from history
-
- CTRL-D command line completion (see |cmdline-completion|)
- 'wildchar' option
- command line completion (see |cmdline-completion|)
- CTRL-N command line completion (see |cmdline-completion|)
- CTRL-P command line completion (see |cmdline-completion|)
- CTRL-A command line completion (see |cmdline-completion|)
- CTRL-L command line completion (see |cmdline-completion|)
-
- *c_CTRL-_*
- CTRL-_ a - switch between Hebrew and English keyboard mode, which is
- private to the command line and not related to hkmap.
- This is useful when Hebrew text entry is required in the
- command line, searches, abbreviations, etc. Applies only if
- Vim is compiled with the |+rightleft| feature.
- See |rightleft.txt|.
-
- b - switch between Farsi and English keyboard mode, which is
- private to the command line and not related to fkmap. In
- Farsi keyboard mode the characters are inserted in revese
- insert manner. This is useful when Farsi text entry is
- required in the command line, searches, abbreviations, etc.
- Applies only if Vim is compiled with the |+farsi| feature.
- See |farsi.txt|.
-
- The <Up> and <Down> keys take the current command line as a search string.
- The beginning of the next/previous command lines are compared with this
- string. The first line that matches is the new command line. When typing
- these two keys repeatedly, the same string is used again. For example, this
- can be used to find the previous substitute command: Type ":s" and then <Up>.
- The same could be done by typing <S-Up> a number of times until the desired
- command line is shown. (Note: the shifted arrow keys do not work on all
- terminals)
-
- ==============================================================================
- 2. Command line completion *cmdline-completion*
-
- When editing the command line, a few commands can be used to complete the
- word before the cursor. This is available for:
-
- - Command names: at the start of the command line. Works always.
- - tags: only after the ":tag" command.
- - file names: only after a command that accepts a file name or a setting for
- an option that can be set to a file name. This is called file name
- completion.
- - options: only after the ":set" command.
-
- These are the commands that can be used:
-
- *c_CTRL-D*
- CTRL-D List names that match the pattern in front of the cursor.
- When showing file names, directories are highlighted (see
- 'highlight' option)
- *c_CTRL-I* *c_wildchar* *c_<Tab>*
- 'wildchar' option
- A match is done on the pattern in front of the cursor. The
- match (if there are several, the first match) is inserted
- in place of the pattern. (Note: does not work inside a
- macro, because <Tab> or <Esc> are mostly used as 'wildchar',
- and these have a special meaning in some macros.) When typed
- again and there were multiple matches, the next
- match is inserted. After the last match, the first is used
- again (wrap around).
- *c_CTRL-N*
- CTRL-N After using 'wildchar' which got multiple matches, go to next
- match. Otherwise recall more recent command line from history.
- <S-Tab> *c_CTRL-P* *c_<S-Tab>*
- CTRL-P After using 'wildchar' which got multiple matches, go to
- previous match. Otherwise recall older command line from
- history. <S-Tab> only works with the GUI, on the Amiga and
- with MS-DOS.
- *c_CTRL-A*
- CTRL-A All names that match the pattern in front of the cursor are
- inserted.
- *c_CTRL-L*
- CTRL-L A match is done on the pattern in front of the cursor. If
- there is one match, it is inserted in place of the pattern.
- If there are multiple matches the longest common part is
- inserted in place of the pattern.
-
- The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in
- a previous version <Esc> was used). In the pattern standard wildcards '*' and
- '?' are accepted. '*' matches any string, '?' matches exactly one character.
-
- If you like tcsh's autolist completion, you can use this mapping:
- :cnoremap X <C-L><C-D>
- (Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D)
- This will find the longest match and then list all matching files.
-
- *suffixes*
- For file name completion you can use the 'suffixes' option to set a priority
- between files with almost the same name. If there are multiple matches,
- those files with an extension that is in the 'suffixes' option are ignored.
- The default is ".bak,~,.o,.h,.info,.swp", which means that files ending in
- ".bak", "~", ".o", ".h", ".info" and ".swp" are sometimes ignored. It is
- impossible to ignore suffixes with two dots. Examples:
-
- pattern: files: match: ~
- test* test.c test.h test.o test.c
- test* test.h test.o test.h and test.o
- test* test.i test.h test.c test.i and test.c
-
- If there is more than one matching file (after ignoring the ones matching
- the 'suffixes' option) the first file name is inserted. You can see that
- there is only one match when you type 'wildchar' twice and the completed
- match stays the same. You can get to the other matches by entering
- 'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with
- extensions matching the 'suffixes' option.
-
- The old value of an option can be obtained by hitting 'wildchar' just after
- the '='. For example, typing 'wildchar' after ":set dir=" will insert the
- current value of 'dir'. This overrules file name completion for the options
- that take a file name.
-
- If you would like using <S-Tab> for CTRL-P in an xterm, put this command in
- your .cshrc:
- > xmodmap -e "keysym Tab = Tab Find"
- And this in your .vimrc:
- > cmap <Esc>[1~ <C-P> (<C-P> is CTRL-P)
-
- ==============================================================================
- 3. Ex command lines *cmdline-lines*
-
- The Ex commands have a few specialties:
-
- *:quote*
- '"' at the start of a line causes the whole line to be ignored. '"'
- after a command causes the rest of the line to be ignored. This can be used
- to add comments. Example:
- > :set ai "set 'autoindent' option
- It is not possible to add a comment to a shell command ":!cmd" or to the
- ":map" command and friends, because they see the '"' as part of their
- argument.
-
- *:bar*
- '|' can be used to separate commands, so you can give multiple commands in one
- line. If you want to use '|' as an argument, precede it with '\'.
-
- These commands see the '|' as their argument, and can therefore not be
- followed by another command:
- :autocmd
- :global
- :normal
- :perl
- :perldo
- :pyfile
- :python
- :read !
- :vglobal
- :write !
- :[range]!
-
- Note that this is confusing (inherited from Vi): With ":g" the '|' is included
- in the command, with ":s" it is not.
-
- To be able to use another command anyway, use the ":execute" command.
- Example (append the output of "ls" and jump to the first line):
- > :execute 'r !ls' | '[
-
- There is one exception: When the 'b' flag is present in 'cpoptions', with the
- ":map" and ":abbr" commands and friends CTRL-V needs to be used instead of
- '\'. You can also use "<Bar>" instead. See also |map_bar|.
-
- Examples:
- > :!ls | wc view the output of two commands
- > :r !ls | wc insert the same output in the text
- > :%g/foo/p|> moves all matching lines one shiftwidth
- > :%s/foo/bar/|> moves one line one shiftwidth
- > :map q 10^V| map "q" to "10|"
- > :map q 10\| map \ l map "q" to "10\" and map "\" to "l"
- > (when 'b' is present in 'cpoptions')
-
- You can also use <NL> to separate commands in the same way as with '|'. To
- insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the
- preferred method. But for external commands a <NL> must be used, because a
- '|' is included in the external command. To avoid the special meaning of <NL>
- it must be preceded with a backslash. Example:
- > :r !date<NL>-join
- This reads the current date into the file and joins it with the previous line.
-
- Note that when the command before the '|' generates an error, the following
- commands will not be executed.
-
-
- Because of Vi compatibility the following strange commands are supported:
- > :| print current line (like ":p")
- > :3| print line 3 (like ":3p")
- > :3 goto line 3
-
- A colon is allowed between the range and the command name. It is ignored
- (this is Vi compatible). For example:
- > :1,$:s/pat/string
-
- When the character '%' or '#' is used where a file name is expected, they are
- expanded to the current and alternate file name (see the chapter "editing
- files" |:_%| |:_#|).
-
- Embedded spaces in file names are allowed on the Amiga if one file name is
- expected as argument. Trailing spaces will be ignored, unless escaped with a
- backslash or CTRL-V. Note that the ":next" command uses spaces to separate
- file names. Escape the spaces to include them in a file name. Example:
- > :next foo\ bar goes\ to school\
- starts editing the three files "foo bar", "goes to" and "school ".
-
- When you want to use the special characters '"' or '|' in a command, or want
- to use '%' or '#' in a file name, precede them with a backslash. The
- backslash is not required in a range and in the ":substitute" command.
-
- *:_!*
- The '!' (bang) character after an Ex command makes the command behave in a
- different way. The '!' should be placed immediately after the command, without
- any blanks in between. If you insert blanks the '!' will be seen as an
- argument for the command, which has a different meaning. For example:
- :w! name write the current buffer to file "name", overwriting
- any existing file
- :w !name send the current buffer as standard input to command
- "name"
-
- ==============================================================================
- 4. Ex command line ranges *cmdline-ranges* *[range]*
-
- Some Ex commands accept a line range in front of them. This is noted as
- [range]. It consists of one or more line specifiers, separated with ',' or
- ';'.
-
- *:,* *:;*
- When separated with ';' the cursor position will be set to that line
- before interpreting the next line specifier. This doesn't happen for ','.
- Examples:
- > 4,/this line/ from line 4 till match with "this line" after
- > the cursor line.
- > 5;/that line/ from line 5 till match with "that line" after
- > line 5.
-
- The default line specifier for most commands is the cursor position, but the
- commands ":write" and ":global" have the whole file (1,$) as default.
-
- If more line specifiers are given than required for the command, the first
- one(s) will be ignored.
-
- Line numbers may be specified with: *:range*
- {number} an absolute line number
- . the current line *:.*
- $ the last line in the file *:$*
- % equal to 1,$ (the entire file) *:%*
- * equal to '<,'> (the Visual area) *:star*
- 't position of mark t (lower case) *:'*
- /{pattern}[/] the next line where {pattern} matches *:/*
- ?{pattern}[?] the previous line where {pattern} matches *:?*
- \/ the next line where the previously used search
- pattern matches
- \? the previous line where the previously used search
- pattern matches
- \& the next line where the previously used substitute
- pattern matches
-
- Each may be followed (several times) by '+' or '-' and an optional number.
- This number is added or subtracted from the preceding line number. If the
- number is omitted, 1 is used.
-
- The "/" and "?" after {pattern} are required to separate the pattern from
- anything that follows.
-
- The "/" and "?" may be preceded with another address. The search starts from
- there. The difference from using ';' is that the cursor isn't moved.
- Examples:
- > /pat1//pat2/ Find line containing "pat2" after line containing
- > "pat1", without moving the cursor.
- > 7;/pat2/ Find line containing "pat2", after line 7, leaving
- > the cursor in line 7.
-
- The {number} must be between 0 and the number of lines in the file. A 0 is
- interpreted as a 1, except with the commands tag, pop and read.
-
- Examples:
- > .+3 three lines below the cursor
- > /that/+1 the line below the next line containing "that"
- > .,$ from current line until end of file
- > 0;/that the first line containing "that"
-
- Some commands allow for a count after the command. This count is used as the
- number of lines to be used, starting with the line given in the last line
- specifier (the default is the cursor line). The commands that accept a count
- are the ones that use a range but do not have a file name argument (because
- a file name can also be a number).
-
- Examples:
- > :s/x/X/g 5 substitute 'x' by 'X' in the current line and four
- > following lines
- > :23d 4 delete lines 23, 24, 25 and 26
-
- A range should have the lower line number first. If this is not the case, Vim
- will ask you if it should swap the line numbers. This is not done within the
- global command ":g".
-
- *N:*
- When giving a count before entering ":", this is translated into:
- :.,.+(count - 1)
- In words: The 'count' lines at and after the cursor. Example: To delete
- three lines:
- > 3:d<CR> is translated into: .,.+2d<CR>
-
- *v_:*
- {Visual}: Starts a command line with the Visual selected lines as a
- range. The code ":'<,'>" is used for this range, which makes
- it possible to select a similar line from the command line
- history for repeating a command on different Visually selected
- lines.
-
- ==============================================================================
- 5. Ex special characters *cmdline-special*
-
- In Ex commands, at places where a file name can be used, the following
- characters have a special meaning. These can also be used in the expression
- function expand() |expand()|.
- % is replaced with the current file name *:_%*
- # is replaced with the alternate file name *:_#*
- #n (where n is a number) is replaced with the file name of
- buffer n. "#0" is the same as "#"
-
- To avoid the special meaning of '%' and '#' insert a backslash before it.
- Detail: The special meaning is always escaped when there is a backslash before
- it, no matter how many backslashes.
- you type: result ~
- # alternate.file
- \# #
- \\# \#
-
- *:<cword>* *:<cWORD>* *:<cfile>* *<cfile>*
- *:<sfile>* *<sfile>* *:<afile>* *<afile>*
- Note: the next four are typed literally, these are not special keys!
- <cword> is replaced with the word under the cursor
- <cWORD> is replaced with the WORD under the cursor (see |WORD|)
- <cfile> is replaced with the path name under the cursor
- <afile> when executing autocommands, is replaced with the file name
- for a file read or write
- <sfile> when executing a ":source" command, is replaced with the
- file name of the sourced file.
-
- *filename-modifiers* *:_%:* *::p* *::h* *::t* *::r* *::e*
- After "%", "#", "#n", "<cfile>", "<sfile>" or "<afile>" modifiers can be given
- (in this order):
- :p Make file name a full path. Must be the first modifier.
- :h Head of the file name (the last component and any
- separators removed). Cannot be used with :e, :r or :t.
- Can be repeated to remove several components at the end.
- When the file name is an absolute path (starts with "/" for
- Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga),
- that part is not removed. When there is no head (path is
- relative to current directory) the result is empty.
- :t Tail of the file name (last component of the name). Must
- precede any :r or :e.
- :r Root of the file name (the last extension removed). When
- there is only an extension (file name that starts with
- '.', e.g., ".vimrc"), it is not removed. Can be repeated to
- remove several extensions (last one first).
- :e Extension of the file name. Only makes sense when used
- alone. When there is no extension the result is empty.
- When there is only an extension (file name that starts with
- '.'), the result is empty. Can be repeated to include more
- extensions. If there are not enough extensions (but at
- least one) as much as possible are included.
-
- Examples, when the file name is "src/version.c":
- > :p /home/mool/vim/src/version.c
- > :h src
- > :p:h /home/mool/vim/src
- > :p:h:h /home/mool/vim
- > :t version.c
- > :p:t version.c
- > :r src/version
- > :p:r /home/mool/vim/src/version
- > :t:r version
- > :e c
-
- Examples, when the file name is "src/version.c.gz":
- > :p /home/mool/vim/src/version.c.gz
- > :e gz
- > :e:e c.gz
- > :e:e:e c.gz
- > :e:e:r c
- > :r src/version.c
- > :r:e c
- > :r:r src/version
- > :r:r:r src/version
-
- *extension-removal* *:_%<*
- If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file
- name is removed (everything after and including the last '.' in the file
- name). This is included for backwards compatibility with version 3.0, the
- ":r" form is preferred. Examples:
-
- > % current file name
- > %< current file name without extension
- > # alternate file name for current window
- > #< idem, without extension
- > #31 alternate file number 31
- > #31< idem, without extension
- > <cword> word under the cursor
- > <cWORD> WORD under the cursor (see |WORD|)
- > <cfile> path name under the cursor
- > <cfile>< idem, without extension
-
- Note: Where a file name is expected wildcards expansion is done. On Unix the
- shell is used for this. Backticks also work, like in
- :n `echo *.c`
- But expansion is only done if there are any wildcards before expanding the
- '%', '#', etc.. This avoids expanding wildcards inside a file name. If you
- want to expand the result of <cfile>, add a wildcard character to it.
- Examples: (alternate file name is "?readme?")
- command expands to ~
- :e # :e ?readme?
- :e `ls #` :e {files matching "?readme?"}
- :e #.* :e {files matching "?readme?.*"}
- :cd <cfile> :cd {file name under cursor}
- :cd <cfile>* :cd {file name under cursor plus "*" and then expanded}
-
- *filename-backslash*
- For filesystems that use a backslash as directory separator (MS-DOS, Windows,
- OS/2), it's a bit difficult to recognize a backslash that is used to escape
- the special meaning of the next character. The general rule is: If the
- backslash is followed by a normal file name character, it does not have a
- special meaning. Therefore "\file\foo" is a valid file name, you don't have
- to type the backslash twice.
-
- And exception is the '$' sign. It is a valid character in a file name. But
- to avoid a file name like "$home" to be interpreted as an environment variable,
- it needs to be preceded by a backslash. Therefore you need to use "/\$home"
- for the file "$home" in the root directory. A few examples:
-
- FILE NAME INTERPRETED AS ~
- $home expanded to value of environment var $home
- \$home file "$home" in current directory
- /\$home file "$home" in root directory
- \\$home file "\\", followed by expanded $home
-
- vim:tw=78:ts=8:sw=8:
-